//*****************************************************************************
// JFab (http://code.google.com/p/jfab)
// Copyright (c) 2011-2012 JFab.org
// Admin jfab@jeffreythompson.net
//
// See the file "LICENSE.txt" for information on usage and redistribution of
// this file, and for a DISCLAIMER OF ALL WARRANTIES.
//*****************************************************************************

package org.jfab.swingui.decorator;

import javax.swing.Icon;

import org.jfab.swingui.editpane.EditPane;

/**
 * Defines methods required by a code generator decorator.
 * 
 * @param <T> Component type.
 */
public interface Decorator<T>
{
    /**
     * @param childTypeName Child type name, as returned by
     *            getChildSelectionValues().
     */
    void addNode(String childTypeName);

    /**
     * Returns the child of parent at index index in the parent's child array.
     * parent must be a node previously obtained from this data source. This
     * should not return null if index is a valid index for parent (that is
     * index >= 0 && index < getChildCount(parent)).
     * 
     * @param index Index.
     * @return the child of parent at index index.
     */
    Object getChild(final int index);

    /**
     * Returns the number of children of parent. Returns 0 if the node is a leaf
     * or if it has no children. parent must be a node previously obtained from
     * this data source.
     * 
     * @return the number of children of the node parent
     */
    int getChildCount();

    /**
     * @return possible child selection values.
     */
    String[] getChildSelectionValues();

    /**
     * @return the component
     */
    T getComponent();

    /**
     * @return the display name.
     */
    String getDisplayName();

    /**
     * @return an edit pane for this node (may be null).
     */
    EditPane<T> getEditPane();

    /**
     * @return an icon representing this node (may be null).
     */
    Icon getIcon();

    /**
     * Returns the index of child in parent. If either parent or child is null,
     * returns -1. If either parent or child don't belong to this tree model,
     * returns -1.
     * 
     * @param child the node we are interested in.
     * @return the index of the child in the parent, or -1 if either child or
     *         parent are null or don't belong to this tree model.
     */
    int getIndexOfChild(final Object child);

    /**
     * @return the parent (may be null).
     */
    Decorator<?> getParent();

    /**
     * Returns true if node is a leaf. It is possible for this method to return
     * false even if node has no children. A directory in a filesystem, for
     * example, may contain no files; the node representing the directory is not
     * a leaf, but it also has no children.
     * 
     * @return true if node is a leaf.
     */
    boolean isLeaf();

    /**
     * Remove this node from its parent.
     * 
     * @return true if the list contained this.
     */
    boolean removeNode();
}
